home *** CD-ROM | disk | FTP | other *** search
/ Languguage OS 2 / Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO / gnu / elispman.lha / elispman / elisp-5 (.txt) < prev    next >
GNU Info File  |  1993-06-01  |  49KB  |  1,037 lines

  1. This is Info file elisp, produced by Makeinfo-1.55 from the input file
  2. elisp.texi.
  3.    This is edition 2.0 of the GNU Emacs Lisp Reference Manual, for
  4. Emacs Version 19.
  5.    Published by the Free Software Foundation, 675 Massachusetts Avenue,
  6. Cambridge, MA 02139 USA
  7.    Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
  8.    Permission is granted to make and distribute verbatim copies of this
  9. manual provided the copyright notice and this permission notice are
  10. preserved on all copies.
  11.    Permission is granted to copy and distribute modified versions of
  12. this manual under the conditions for verbatim copying, provided that
  13. the entire resulting derived work is distributed under the terms of a
  14. permission notice identical to this one.
  15.    Permission is granted to copy and distribute translations of this
  16. manual into another language, under the above conditions for modified
  17. versions, except that this permission notice may be stated in a
  18. translation approved by the Foundation.
  19. File: elisp,  Node: Case Table,  Prev: Character Case,  Up: Strings and Characters
  20. The Case Table
  21. ==============
  22.    You can customize case conversion by installing a special "case
  23. table".  A case table specifies the mapping between upper case and lower
  24. case letters.  It affects both the string and character case conversion
  25. functions (see the previous section) and those that apply to text in the
  26. buffer (*note Case Changes::.).  Use case table if you are using a
  27. language which has letters that are not the standard ASCII letters.
  28.    A case table is a list of this form:
  29.      (DOWNCASE UPCASE CANONICALIZE EQUIVALENCES)
  30. where each element is either `nil' or a string of length 256.  The
  31. element DOWNCASE says how to map each character to its lower-case
  32. equivalent.  The element UPCASE maps each character to its upper-case
  33. equivalent.  If lower and upper case characters are in one-to-one
  34. correspondence, use `nil' for UPCASE; then Emacs deduces the upcase
  35. table from DOWNCASE.
  36.    For some languages, upper and lower case letters are not in
  37. one-to-one correspondence.  There may be two different lower case
  38. letters with the same upper case equivalent.  In these cases, you need
  39. to specify the maps for both directions.
  40.    The element CANONICALIZE maps each character to a canonical
  41. equivalent; any two characters that are related by case-conversion have
  42. the same canonical equivalent character.
  43.    The element EQUIVALENCES is a map that cyclicly permutes each
  44. equivalence class (of characters with the same canonical equivalent).
  45. (For ordinary ASCII, this would map `a' into `A' and `A' into `a', and
  46. likewise for each set of equivalent characters.)
  47.    You can provide `nil' for both CANONICALIZE and EQUIVALENCES, in
  48. which case both are deduced from DOWNCASE and UPCASE.  Normally, that's
  49. what you should do, when you construct a case table.  But when you look
  50. at the case table that's in use, you will find non-`nil' values for
  51. those components.
  52.    Each buffer has a case table.  Emacs also has a "standard case
  53. table" which is copied into each buffer when you create the buffer.
  54. (Changing the standard case table doesn't affect any existing buffers.)
  55.    Here are the functions for working with case tables:
  56.  - Function: case-table-p OBJECT
  57.      This predicate returns non-`nil' if OBJECT is a valid case table.
  58.  - Function: set-standard-case-table TABLE
  59.      This function makes TABLE the standard case table, so that it will
  60.      apply to any buffers created subsequently.
  61.  - Function: standard-case-table
  62.      This returns the standard case table.
  63.  - Function: current-case-table
  64.      This function returns the current buffer's case table.
  65.  - Function: set-case-table TABLE
  66.      This sets the current buffer's case table to TABLE.
  67.    The following three functions are convenient subroutines for packages
  68. that define non-ASCII character sets.  They modify a string
  69. DOWNCASE-TABLE provided as an argument; this should be a string to be
  70. used as the DOWNCASE part of a case table.  They also modify two syntax
  71. tables, the standard syntax table and the Text mode syntax table.
  72. (*Note Syntax Tables::.)
  73.  - Function: set-case-syntax-pair UC LC DOWNCASE-TABLE
  74.      This function specifies a pair of corresponding letters, one upper
  75.      case and one lower case.
  76.  - Function: set-case-syntax-delims L R DOWNCASE-TABLE
  77.      This function makes characters L and R a matching pair of
  78.      case-invariant delimiters.
  79.  - Function: set-case-syntax CHAR SYNTAX DOWNCASE-TABLE
  80.      This function makes CHAR case-invariant, with syntax SYNTAX.
  81.  - Command: describe-buffer-case-table
  82.      This command displays a description of the contents of the current
  83.      buffer's case table.
  84.    You can load the library `iso-syntax' to set up the syntax and case
  85. table for the 256 bit ISO Latin 1 character set.
  86. File: elisp,  Node: Lists,  Next: Sequences Arrays Vectors,  Prev: Strings and Characters,  Up: Top
  87. Lists
  88. *****
  89.    A "list" represents a sequence of zero or more elements (which may
  90. be any Lisp objects).  The important difference between lists and
  91. vectors is that two or more lists can share part of their structure; in
  92. addition, you can insert or delete elements in a list without copying
  93. the whole list.
  94. * Menu:
  95. * Cons Cells::          How lists are made out of cons cells.
  96. * Lists as Boxes::                 Graphical notation to explain lists.
  97. * List-related Predicates::        Is this object a list?  Comparing two lists.
  98. * List Elements::       Extracting the pieces of a list.
  99. * Building Lists::      Creating list structure.
  100. * Modifying Lists::     Storing new pieces into an existing list.
  101. * Sets And Lists::      A list can represent a finite mathematical set.
  102. * Association Lists::   A list can represent a finite relation or mapping.
  103. File: elisp,  Node: Cons Cells,  Next: Lists as Boxes,  Prev: Lists,  Up: Lists
  104. Lists and Cons Cells
  105. ====================
  106.    Lists in Lisp are not a primitive data type; they are built up from
  107. "cons cells".  A cons cell is a data object which represents an ordered
  108. pair.  It records two Lisp objects, one labeled as the CAR, and the
  109. other labeled as the CDR.  (These names are traditional.)
  110.    A list is made by chaining cons cells together, one cons cell per
  111. element.  By convention, the CARs of the cons cells are the elements of
  112. the list, and the CDRs are used to chain the list: the CDR of each cons
  113. cell is the following cons cell.  The CDR of the last cons cell is
  114. `nil'.  This asymmetry between the CAR and the CDR is entirely a matter
  115. of convention; at the level of cons cells, the CAR and CDR slots have
  116. the same characteristics.
  117.    The symbol `nil' is considered a list as well as a symbol; it is the
  118. list with no elements.  For convenience, the symbol `nil' is considered
  119. to have `nil' as its CDR (and also as its CAR).
  120.    The CDR of any nonempty list L is a list containing all the elements
  121. of L except the first.
  122. File: elisp,  Node: Lists as Boxes,  Next: List-related Predicates,  Prev: Cons Cells,  Up: Lists
  123. Lists as Linked Pairs of Boxes
  124. ==============================
  125.    A cons cell can be illustrated as a pair of boxes.  The first box
  126. represents the CAR and the second box represents the CDR.  Here is an
  127. illustration of the two-element list, `(tulip lily)', made from two
  128. cons cells:
  129.       ---------------         ---------------
  130.      | car   | cdr   |       | car   | cdr   |
  131.      | tulip |   o---------->| lily  |  nil  |
  132.      |       |       |       |       |       |
  133.       ---------------         ---------------
  134.    Each pair of boxes represents a cons cell.  Each box "refers to",
  135. "points to" or "contains" a Lisp object.  (These terms are synonymous.)
  136. The first box, which is the CAR of the first cons cell, contains the
  137. symbol `tulip'.  The arrow from the CDR of the first cons cell to the
  138. second cons cell indicates that the CDR of the first cons cell points
  139. to the second cons cell.
  140.    The same list can be illustrated in a different sort of box notation
  141. like this:
  142.          ___ ___      ___ ___
  143.         |___|___|--> |___|___|--> nil
  144.           |            |
  145.           |            |
  146.            --> tulip    --> lily
  147.    Here is a more complex illustration, this time of the three-element
  148. list, `((pine needles) oak maple)', the first element of which is a
  149. two-element list:
  150.          ___ ___      ___ ___      ___ ___
  151.         |___|___|--> |___|___|--> |___|___|--> nil
  152.           |            |            |
  153.           |            |            |
  154.           |             --> oak      --> maple
  155.           |
  156.           |     ___ ___      ___ ___
  157.            --> |___|___|--> |___|___|--> nil
  158.                  |            |
  159.                  |            |
  160.                   --> pine     --> needles
  161.    The same list is represented in the first box notation like this:
  162.       --------------       --------------       --------------
  163.      | car   | cdr  |     | car   | cdr  |     | car   | cdr  |
  164.      |   o   |   o------->| oak   |   o------->| maple |  nil |
  165.      |   |   |      |     |       |      |     |       |      |
  166.       -- | ---------       --------------       --------------
  167.          |
  168.          |
  169.          |        --------------       ----------------
  170.          |       | car   | cdr  |     | car     | cdr  |
  171.           ------>| pine  |   o------->| needles |  nil |
  172.                  |       |      |     |         |      |
  173.                   --------------       ----------------
  174.    *Note List Type::, for the read and print syntax of lists, and for
  175. more "box and arrow" illustrations of lists.
  176. File: elisp,  Node: List-related Predicates,  Next: List Elements,  Prev: Lists as Boxes,  Up: Lists
  177. Predicates on Lists
  178. ===================
  179.    The following predicates test whether a Lisp object is an atom, is a
  180. cons cell or is a list, or whether it is the distinguished object `nil'.
  181. (Many of these tests can be defined in terms of the others, but they are
  182. used so often that it is worth having all of them.)
  183.  - Function: consp OBJECT
  184.      This function returns `t' if OBJECT is a cons cell, `nil'
  185.      otherwise.  `nil' is not a cons cell, although it *is* a list.
  186.  - Function: atom OBJECT
  187.      This function returns `t' if OBJECT is an atom, `nil' otherwise.
  188.      All objects except cons cells are atoms.  The symbol `nil' is an
  189.      atom and is also a list; it is the only Lisp object which is both.
  190.           (atom OBJECT) == (not (consp OBJECT))
  191.  - Function: listp OBJECT
  192.      This function returns `t' if OBJECT is a cons cell or `nil'.
  193.      Otherwise, it returns `nil'.
  194.           (listp '(1))
  195.                => t
  196.           (listp '())
  197.                => t
  198.  - Function: nlistp OBJECT
  199.      This function is the opposite of `listp': it returns `t' if OBJECT
  200.      is not a list.  Otherwise, it returns `nil'.
  201.           (listp OBJECT) == (not (nlistp OBJECT))
  202.  - Function: null OBJECT
  203.      This function returns `t' if OBJECT is `nil', and returns `nil'
  204.      otherwise.  This function is identical to `not', but as a matter
  205.      of clarity we use `null' when OBJECT is considered a list and
  206.      `not' when it is considered a truth value (see `not' in *Note
  207.      Combining Conditions::).
  208.           (null '(1))
  209.                => nil
  210.           (null '())
  211.                => t
  212. File: elisp,  Node: List Elements,  Next: Building Lists,  Prev: List-related Predicates,  Up: Lists
  213. Accessing Elements of Lists
  214. ===========================
  215.  - Function: car CONS-CELL
  216.      This function returns the value pointed to by the first pointer of
  217.      the cons cell CONS-CELL.  Expressed another way, this function
  218.      returns the CAR of CONS-CELL.
  219.      As a special case, if CONS-CELL is `nil', then `car' is defined to
  220.      return `nil'; therefore, any list is a valid argument for `car'.
  221.      An error is signaled if the argument is not a cons cell or `nil'.
  222.           (car '(a b c))
  223.                => a
  224.           (car '())
  225.                => nil
  226.  - Function: cdr CONS-CELL
  227.      This function returns the value pointed to by the second pointer of
  228.      the cons cell CONS-CELL.  Expressed another way, this function
  229.      returns the CDR of CONS-CELL.
  230.      As a special case, if CONS-CELL is `nil', then `cdr' is defined to
  231.      return `nil'; therefore, any list is a valid argument for `cdr'.
  232.      An error is signaled if the argument is not a cons cell or `nil'.
  233.           (cdr '(a b c))
  234.                => (b c)
  235.           (cdr '())
  236.                => nil
  237.  - Function: car-safe OBJECT
  238.      This function lets you take the CAR of a cons cell while avoiding
  239.      errors for other data types.  It returns the CAR of OBJECT if
  240.      OBJECT is a cons cell, `nil' otherwise.  This is in contrast to
  241.      `car', which signals an error if OBJECT is not a list.
  242.           (car-safe OBJECT)
  243.           ==
  244.           (let ((x OBJECT))
  245.             (if (consp x)
  246.                 (car x)
  247.               nil))
  248.  - Function: cdr-safe OBJECT
  249.      This function lets you take the CDR of a cons cell while avoiding
  250.      errors for other data types.  It returns the CDR of OBJECT if
  251.      OBJECT is a cons cell, `nil' otherwise.  This is in contrast to
  252.      `cdr', which signals an error if OBJECT is not a list.
  253.           (cdr-safe OBJECT)
  254.           ==
  255.           (let ((x OBJECT))
  256.             (if (consp x)
  257.                 (cdr x)
  258.               nil))
  259.  - Function: nth N LIST
  260.      This function returns the Nth element of LIST.  Elements are
  261.      numbered starting with zero, so the CAR of LIST is element number
  262.      zero.  If the length of LIST is N or less, the value is `nil'.
  263.      If N is less than zero, then the first element is returned.
  264.           (nth 2 '(1 2 3 4))
  265.                => 3
  266.           (nth 10 '(1 2 3 4))
  267.                => nil
  268.           (nth -3 '(1 2 3 4))
  269.                => 1
  270.           
  271.           (nth n x) == (car (nthcdr n x))
  272.  - Function: nthcdr N LIST
  273.      This function returns the Nth cdr of LIST.  In other words, it
  274.      removes the first N links of LIST and returns what follows.
  275.      If N is less than or equal to zero, then all of LIST is returned.
  276.      If the length of LIST is N or less, the value is `nil'.
  277.           (nthcdr 1 '(1 2 3 4))
  278.                => (2 3 4)
  279.           (nthcdr 10 '(1 2 3 4))
  280.                => nil
  281.           (nthcdr -3 '(1 2 3 4))
  282.                => (1 2 3 4)
  283. File: elisp,  Node: Building Lists,  Next: Modifying Lists,  Prev: List Elements,  Up: Lists
  284. Building Cons Cells and Lists
  285. =============================
  286.    Many functions build lists, as lists reside at the very heart of
  287. Lisp.  `cons' is the fundamental list-building function; however, it is
  288. interesting to note that `list' is used more times in the source code
  289. for Emacs than `cons'.
  290.  - Function: cons OBJECT1 OBJECT2
  291.      This function is the fundamental function used to build new list
  292.      structure.  It creates a new cons cell, making OBJECT1 the CAR,
  293.      and OBJECT2 the CDR.  It then returns the new cons cell.  The
  294.      arguments OBJECT1 and OBJECT2 may be any Lisp objects, but most
  295.      often OBJECT2 is a list.
  296.           (cons 1 '(2))
  297.                => (1 2)
  298.           (cons 1 '())
  299.                => (1)
  300.           (cons 1 2)
  301.                => (1 . 2)
  302.      `cons' is often used to add a single element to the front of a
  303.      list.  This is called "consing the element onto the list".  For
  304.      example:
  305.           (setq list (cons newelt list))
  306.      Note that there is no conflict between the variable named `list'
  307.      used in this example and the function named `list' described below;
  308.      any symbol can serve both functions.
  309.  - Function: list &rest OBJECTS
  310.      This function creates a list with OBJECTS as its elements.  The
  311.      resulting list is always `nil'-terminated.  If no OBJECTS are
  312.      given, the empty list is returned.
  313.           (list 1 2 3 4 5)
  314.                => (1 2 3 4 5)
  315.           (list 1 2 '(3 4 5) 'foo)
  316.                => (1 2 (3 4 5) foo)
  317.           (list)
  318.                => nil
  319.  - Function: make-list LENGTH OBJECT
  320.      This function creates a list of length LENGTH, in which all the
  321.      elements have the identical value OBJECT.  Compare `make-list'
  322.      with `make-string' (*note Creating Strings::.).
  323.           (make-list 3 'pigs)
  324.                => (pigs pigs pigs)
  325.           (make-list 0 'pigs)
  326.                => nil
  327.  - Function: append &rest SEQUENCES
  328.      This function returns a list containing all the elements of
  329.      SEQUENCES.  The SEQUENCES may be lists, vectors, strings, or
  330.      integers.  All arguments except the last one are copied, so none
  331.      of them are altered.
  332.      The final argument to `append' may be any object but it is
  333.      typically a list.  The final argument is not copied or converted;
  334.      it becomes part of the structure of the new list.
  335.      Here is an example:
  336.           (setq trees '(pine oak))
  337.                => (pine oak)
  338.           (setq more-trees (append '(maple birch) trees))
  339.                => (maple birch pine oak)
  340.           
  341.           trees
  342.                => (pine oak)
  343.           more-trees
  344.                => (maple birch pine oak)
  345.           (eq trees (cdr (cdr more-trees)))
  346.                => t
  347.      You can see what happens by looking at a box diagram.  The variable
  348.      `trees' is set to the list `(pine oak)' and then the variable
  349.      `more-trees' is set to the list `(maple birch pine oak)'.
  350.      However, the variable `trees' continues to refer to the original
  351.      list:
  352.           more-trees                trees
  353.           |                           |
  354.           |     ___ ___      ___ ___   -> ___ ___      ___ ___
  355.            --> |___|___|--> |___|___|--> |___|___|--> |___|___|--> nil
  356.                  |            |            |            |
  357.                  |            |            |            |
  358.                   --> maple    -->birch     --> pine     --> oak
  359.      An empty sequence contributes nothing to the value returned by
  360.      `append'.  As a consequence of this, a final `nil' argument forces
  361.      a copy of the previous argument.
  362.           trees
  363.                => (pine oak)
  364.           (setq wood (append trees ()))
  365.                => (pine oak)
  366.           wood
  367.                => (pine oak)
  368.           (eq wood trees)
  369.                => nil
  370.      This once was the standard way to copy a list, before the function
  371.      `copy-sequence' was invented.  *Note Sequences Arrays Vectors::.
  372.      With the help of `apply', we can append all the lists in a list of
  373.      lists:
  374.           (apply 'append '((a b c) nil (x y z) nil))
  375.                => (a b c x y z)
  376.      If no SEQUENCES are given, `nil' is returned:
  377.           (append)
  378.                => nil
  379.      In the special case where one of the SEQUENCES is an integer (not
  380.      a sequence of integers), it is first converted to a string of
  381.      digits making up the decimal print representation of the integer.
  382.      This special case exists for compatibility with Mocklisp, and we
  383.      don't recommend you take advantage of it.  If you want to convert
  384.      an integer in this way, use `format' (*note Formatting Strings::.)
  385.      or `number-to-string' (*note String Conversion::.).
  386.           (setq trees '(pine oak))
  387.                => (pine oak)
  388.           (char-to-string 54)
  389.                => "6"
  390.           (setq longer-list (append trees 6 '(spruce)))
  391.                => (pine oak 54 spruce)
  392.           (setq x-list (append trees 6 6))
  393.                => (pine oak 54 . 6)
  394.      See `nconc' in *Note Rearrangement::, for another way to join lists
  395.      without copying.
  396.  - Function: reverse LIST
  397.      This function creates a new list whose elements are the elements of
  398.      LIST, but in reverse order.  The original argument LIST is *not*
  399.      altered.
  400.           (setq x '(1 2 3 4))
  401.                => (1 2 3 4)
  402.           (reverse x)
  403.                => (4 3 2 1)
  404.           x
  405.                => (1 2 3 4)
  406. File: elisp,  Node: Modifying Lists,  Next: Sets And Lists,  Prev: Building Lists,  Up: Lists
  407. Modifying Existing List Structure
  408. =================================
  409.    You can modify the CAR and CDR contents of a cons cell with the
  410. primitives `setcar' and `setcdr'.
  411.      Common Lisp note: Common Lisp uses functions `rplaca' and `rplacd'
  412.      to alter list structure; they change structure the same way as
  413.      `setcar' and `setcdr', but the Common Lisp functions return the
  414.      cons cell while `setcar' and `setcdr' return the new CAR or CDR.
  415. * Menu:
  416. * Setcar::          Replacing an element in a list.
  417. * Setcdr::          Replacing part of the list backbone.
  418.                       This can be used to remove or add elements.
  419. * Rearrangement::   Reordering the elements in a list; combining lists.
  420. File: elisp,  Node: Setcar,  Next: Setcdr,  Prev: Modifying Lists,  Up: Modifying Lists
  421. Altering List Elements with `setcar'
  422. ------------------------------------
  423.    Changing the CAR of a cons cell is done with `setcar' and replaces
  424. one element of a list with a different element.
  425.  - Function: setcar CONS OBJECT
  426.      This function stores OBJECT as the new CAR of CONS, replacing its
  427.      previous CAR.  It returns the value OBJECT.  For example:
  428.           (setq x '(1 2))
  429.                => (1 2)
  430.           (setcar x '4)
  431.                => 4
  432.           x
  433.                => (4 2)
  434.    When a cons cell is part of the shared structure of several lists,
  435. storing a new CAR into the cons changes one element of each of these
  436. lists.  Here is an example:
  437.      ;; Create two lists that are partly shared.
  438.      (setq x1 '(a b c))
  439.           => (a b c)
  440.      (setq x2 (cons 'z (cdr x1)))
  441.           => (z b c)
  442.      
  443.      ;; Replace the CAR of a shared link.
  444.      (setcar (cdr x1) 'foo)
  445.           => foo
  446.      x1                           ; Both lists are changed.
  447.           => (a foo c)
  448.      x2
  449.           => (z foo c)
  450.      
  451.      ;; Replace the CAR of a link that is not shared.
  452.      (setcar x1 'baz)
  453.           => baz
  454.      x1                           ; Only one list is changed.
  455.           => (baz foo c)
  456.      x2
  457.           => (z foo c)
  458.    Here is a graphical depiction of the shared structure of the two
  459. lists X1 and X2, showing why replacing `b' changes them both:
  460.              ___ ___        ___ ___      ___ ___
  461.      x1---> |___|___|----> |___|___|--> |___|___|--> nil
  462.               |        -->   |            |
  463.               |       |      |            |
  464.                --> a  |       --> b        --> c
  465.                       |
  466.             ___ ___   |
  467.      x2--> |___|___|--
  468.              |
  469.              |
  470.               --> z
  471.    Here is an alternative form of box diagram, showing the same
  472. relationship:
  473.      x1:
  474.       --------------       --------------       --------------
  475.      | car   | cdr  |     | car   | cdr  |     | car   | cdr  |
  476.      |   a   |   o------->|   b   |   o------->|   c   |  nil |
  477.      |       |      |  -->|       |      |     |       |      |
  478.       --------------  |    --------------       --------------
  479.                       |
  480.      x2:              |
  481.       --------------  |
  482.      | car   | cdr  | |
  483.      |   z   |   o----
  484.      |       |      |
  485.       --------------
  486. File: elisp,  Node: Setcdr,  Next: Rearrangement,  Prev: Setcar,  Up: Modifying Lists
  487. Altering the CDR of a List
  488. --------------------------
  489.    The lowest-level primitive for modifying a CDR is `setcdr':
  490.  - Function: setcdr CONS OBJECT
  491.      This function stores OBJECT into the cdr of CONS.  The value
  492.      returned is OBJECT, not CONS.
  493.    Here is an example of replacing the CDR of a list with a different
  494. list.  All but the first element of the list are removed in favor of a
  495. different sequence of elements.  The first element is unchanged,
  496. because it resides in the CAR of the list, and is not reached via the
  497.      (setq x '(1 2 3))
  498.           => (1 2 3)
  499.      (setcdr x '(4))
  500.           => (4)
  501.      x
  502.           => (1 4)
  503.    You can delete elements from the middle of a list by altering the
  504. CDRs of the cons cells in the list.  For example, here we delete the
  505. second element, `b', from the list `(a b c)', by changing the CDR of
  506. the first cell:
  507.      (setq x1 '(a b c))
  508.           => (a b c)
  509.      (setcdr x1 (cdr (cdr x1)))
  510.           => (c)
  511.      x1
  512.           => (a c)
  513.    Here is the result in box notation:
  514.                         --------------------
  515.                        |                    |
  516.       --------------   |   --------------   |    --------------
  517.      | car   | cdr  |  |  | car   | cdr  |   -->| car   | cdr  |
  518.      |   a   |   o-----   |   b   |   o-------->|   c   |  nil |
  519.      |       |      |     |       |      |      |       |      |
  520.       --------------       --------------        --------------
  521. The second cons cell, which previously held the element `b', still
  522. exists and its CAR is still `b', but it no longer forms part of this
  523. list.
  524.    It is equally easy to insert a new element by changing CDRs:
  525.      (setq x1 '(a b c))
  526.           => (a b c)
  527.      (setcdr x1 (cons 'd (cdr x1)))
  528.           => (d b c)
  529.      x1
  530.           => (a d b c)
  531.    Here is this result in box notation:
  532.      --------------        -------------       -------------
  533.      | car  | cdr   |      | car  | cdr  |     | car  | cdr  |
  534.      |   a  |   o   |   -->|   b  |   o------->|   c  |  nil |
  535.      |      |   |   |  |   |      |      |     |      |      |
  536.       --------- | --   |    -------------       -------------
  537.                 |      |
  538.           -----         --------
  539.          |                      |
  540.          |    ---------------   |
  541.          |   | car   | cdr   |  |
  542.           -->|   d   |   o------
  543.              |       |       |
  544.               ---------------
  545. File: elisp,  Node: Rearrangement,  Prev: Setcdr,  Up: Modifying Lists
  546. Functions that Rearrange Lists
  547. ------------------------------
  548.    Here are some functions that rearrange lists "destructively" by
  549. modifying the CDRs of their component cons cells.  We call these
  550. functions "destructive" because the original lists passed as arguments
  551. to them are chewed up to produce a new list that is subsequently
  552. returned.
  553.  - Function: nconc &rest LISTS
  554.      This function returns a list containing all the elements of LISTS.
  555.      Unlike `append' (*note Building Lists::.), the LISTS are *not*
  556.      copied.  Instead, the last CDR of each of the LISTS is changed to
  557.      refer to the following list.  The last of the LISTS is not
  558.      altered.  For example:
  559.           (setq x '(1 2 3))
  560.                => (1 2 3)
  561.           (nconc x '(4 5))
  562.                => (1 2 3 4 5)
  563.           x
  564.                => (1 2 3 4 5)
  565.      Since the last argument of `nconc' is not itself modified, it is
  566.      reasonable to use a constant list, such as `'(4 5)', as is done in
  567.      the above example.  For the same reason, the last argument need
  568.      not be a list:
  569.           (setq x '(1 2 3))
  570.                => (1 2 3)
  571.           (nconc x 'z)
  572.                => (1 2 3 . z)
  573.           x
  574.                => (1 2 3 . z)
  575.      A common pitfall is to use a quoted constant list as a non-last
  576.      argument to `nconc'.  If you do this, your program will change
  577.      each time you run it!  Here is what happens:
  578.           (defun add-foo (x)            ; This function should add
  579.             (nconc '(foo) x))           ;   `foo' to the front of its arg.
  580.           (symbol-function 'add-foo)
  581.                => (lambda (x) (nconc (quote (foo)) x))
  582.           (setq xx (add-foo '(1 2)))    ; It seems to work.
  583.                => (foo 1 2)
  584.           (setq xy (add-foo '(3 4)))    ; What happened?
  585.                => (foo 1 2 3 4)
  586.           (eq xx xy)
  587.                => t
  588.           (symbol-function 'add-foo)
  589.                => (lambda (x) (nconc (quote (foo 1 2 3 4) x)))
  590.  - Function: nreverse LIST
  591.      This function reverses the order of the elements of LIST.  Unlike
  592.      `reverse', `nreverse' alters its argument destructively by
  593.      reversing the CDRs in the cons cells forming the list.  The cons
  594.      cell which used to be the last one in LIST becomes the first cell
  595.      of the value.
  596.      For example:
  597.           (setq x '(1 2 3 4))
  598.                => (1 2 3 4)
  599.           x
  600.                => (1 2 3 4)
  601.           (nreverse x)
  602.                => (4 3 2 1)
  603.           ;; The cell that was first is now last.
  604.           x
  605.                => (1)
  606.      To avoid confusion, we usually store the result of `nreverse' back
  607.      in the same variable which held the original list:
  608.           (setq x (nreverse x))
  609.      Here is the `nreverse' of our favorite example, `(a b c)',
  610.      presented graphically:
  611.           Original list head:                       Reversed list:
  612.            -------------        -------------        ------------
  613.           | car  | cdr  |      | car  | cdr  |      | car | cdr  |
  614.           |   a  |  nil |<--   |   b  |   o  |<--   |   c |   o  |
  615.           |      |      |   |  |      |   |  |   |  |     |   |  |
  616.            -------------    |   --------- | -    |   -------- | -
  617.                             |             |      |            |
  618.                              -------------        ------------
  619.  - Function: sort LIST PREDICATE
  620.      This function sorts LIST stably, though destructively, and returns
  621.      the sorted list.  It compares elements using PREDICATE.  A stable
  622.      sort is one in which elements with equal sort keys maintain their
  623.      relative order before and after the sort.  Stability is important
  624.      when successive sorts are used to order elements according to
  625.      different criteria.
  626.      The argument PREDICATE must be a function that accepts two
  627.      arguments.  It is called with two elements of LIST.  To get an
  628.      increasing order sort, the PREDICATE should return `t' if the
  629.      first element is "less than" the second, or `nil' if not.
  630.      The destructive aspect of `sort' is that it rearranges the cons
  631.      cells forming LIST by changing CDRs.  A nondestructive sort
  632.      function would create new cons cells to store the elements in their
  633.      sorted order.  If you wish to sort a list without destroying the
  634.      original, copy it first with `copy-sequence'.
  635.      The CARs of the cons cells are not changed; the cons cell that
  636.      originally contained the element `a' in LIST still has `a' in its
  637.      CAR after sorting, but it now appears in a different position in
  638.      the list due to the change of CDRs.  For example:
  639.           (setq nums '(1 3 2 6 5 4 0))
  640.                => (1 3 2 6 5 4 0)
  641.           (sort nums '<)
  642.                => (0 1 2 3 4 5 6)
  643.           nums
  644.                => (1 2 3 4 5 6)
  645.      Note that the list in `nums' no longer contains 0; this is the same
  646.      cons cell that it was before, but it is no longer the first one in
  647.      the list.  Don't assume a variable that formerly held the argument
  648.      now holds the entire sorted list!  Instead, save the result of
  649.      `sort' and use that.  Most often we store the result back into the
  650.      variable that held the original list:
  651.           (setq nums (sort nums '<))
  652.      *Note Sorting::, for more functions that perform sorting.  See
  653.      `documentation' in *Note Accessing Documentation::, for a useful
  654.      example of `sort'.
  655.    See `delq', in *Note Sets And Lists::, for another function that
  656. modifies cons cells.
  657. File: elisp,  Node: Sets And Lists,  Next: Association Lists,  Prev: Modifying Lists,  Up: Lists
  658. Using Lists as Sets
  659. ===================
  660.    A list can represent an unordered mathematical set--simply consider a
  661. value an element of a set if it appears in the list, and ignore the
  662. order of the list.  To form the union of two sets, use `append' (as
  663. long as you don't mind having duplicate elements).  Other useful
  664. functions for sets include `memq' and `delq', and their `equal'
  665. versions, `member' and `delete'.
  666.      Common Lisp note: Common Lisp has functions `union' (which avoids
  667.      duplicate elements) and `intersection' for set operations, but GNU
  668.      Emacs Lisp does not have them.  You can write them in Lisp if you
  669.      wish.
  670.  - Function: memq OBJECT LIST
  671.      This function tests to see whether OBJECT is a member of LIST.  If
  672.      it is, `memq' returns a list starting with the first occurrence of
  673.      OBJECT.  Otherwise, it returns `nil'.  The letter `q' in `memq'
  674.      says that it uses `eq' to compare OBJECT against the elements of
  675.      the list.  For example:
  676.           (memq 2 '(1 2 3 2 1))
  677.                => (2 3 2 1)
  678.           (memq '(2) '((1) (2)))    ; `(2)' and `(2)' are not `eq'.
  679.                => nil
  680.  - Function: delq OBJECT LIST
  681.      This function removes all elements `eq' to OBJECT from LIST.  The
  682.      letter `q' in `delq' says that it uses `eq' to compare OBJECT
  683.      against the elements of the list, like `memq'.
  684.    When `delq' deletes elements from the front of the list, it does so
  685. simply by advancing down the list and returning a sublist that starts
  686. after those elements:
  687.      (delq 'a '(a b c))
  688.      ==
  689.      (cdr '(a b c))
  690.    When an element to be deleted appears in the middle of the list,
  691. removing it involves changing the CDRs (*note Setcdr::.).
  692.      (setq sample-list '(1 2 3 (4)))
  693.           => (1 2 3 (4))
  694.      (delq 1 sample-list)
  695.           => (2 3 (4))
  696.      sample-list
  697.           => (1 2 3 (4))
  698.      (delq 2 sample-list)
  699.           => (1 3 (4))
  700.      sample-list
  701.           => (1 3 (4))
  702.    Note that `(delq 2 sample-list)' modifies `sample-list' to splice
  703. out the second element, but `(delq 1 sample-list)' does not splice
  704. anything--it just returns a shorter list.  Don't assume that a variable
  705. which formerly held the argument LIST now has fewer elements, or that
  706. it still holds the original list!  Instead, save the result of `delq'
  707. and use that.  Most often we store the result back into the variable
  708. that held the original list:
  709.      (setq flowers (delq 'rose flowers))
  710.    In the following example, the `(4)' that `delq' attempts to match
  711. and the `(4)' in the `sample-list' are not `eq':
  712.      (delq '(4) sample-list)
  713.           => (1 3 (4))
  714.    The following two functions are like `memq' and `delq' but use
  715. `equal' rather than `eq' to compare elements.  They are new in Emacs 19.
  716.  - Function: member OBJECT LIST
  717.      The function `member' tests to see whether OBJECT is a member of
  718.      LIST, comparing members with OBJECT using `equal'.  If OBJECT is a
  719.      member, `memq' returns a list starting with its first occurrence
  720.      in LIST.  Otherwise, it returns `nil'.
  721.      Compare this with `memq':
  722.           (member '(2) '((1) (2)))  ; `(2)' and `(2)' are `equal'.
  723.                => ((2))
  724.           (memq '(2) '((1) (2)))    ; `(2)' and `(2)' are not `eq'.
  725.                => nil
  726.           ;; Two strings with the same contents are `equal'.
  727.           (member "foo" '("foo" "bar"))
  728.                => ("foo" "bar")
  729.  - Function: delete OBJECT LIST
  730.      This function removes all elements `equal' to OBJECT from LIST.
  731.      It is to `delq' as `member' is to `memq': it uses `equal' to
  732.      compare elements with OBJECT, like `member'; when it finds an
  733.      element that matches, it removes the element just as `delq' would.
  734.      For example:
  735.           (delete '(2) '((2) (1) (2)))
  736.                => '((1))
  737.      Common Lisp note: The functions `member' and `delete' in GNU Emacs
  738.      Lisp are derived from Maclisp, not Common Lisp.  The Common Lisp
  739.      versions do not use `equal' to compare elements.
  740. File: elisp,  Node: Association Lists,  Prev: Sets And Lists,  Up: Lists
  741. Association Lists
  742. =================
  743.    An "association list", or "alist" for short, records a mapping from
  744. keys to values.  It is a list of cons cells called "associations": the
  745. CAR of each cell is the "key", and the CDR is the "associated value".
  746. (This usage of "key" is not related to the term "key sequence"; it
  747. means any object which can be looked up in a table.)
  748.    Here is an example of an alist.  The key `pine' is associated with
  749. the value `cones'; the key `oak' is associated with `acorns'; and the
  750. key `maple' is associated with `seeds'.
  751.      '((pine . cones)
  752.        (oak . acorns)
  753.        (maple . seeds))
  754.    The associated values in an alist may be any Lisp objects; so may the
  755. keys.  For example, in the following alist, the symbol `a' is
  756. associated with the number `1', and the string `"b"' is associated with
  757. the *list* `(2 3)', which is the CDR of the alist element:
  758.      ((a . 1) ("b" 2 3))
  759.    Sometimes it is better to design an alist to store the associated
  760. value in the CAR of the CDR of the element.  Here is an example:
  761.      '((rose red) (lily white) (buttercup yellow)))
  762. Here we regard `red' as the value associated with `rose'.  One
  763. advantage of this method is that you can store other related
  764. information--even a list of other items--in the CDR of the CDR.  One
  765. disadvantage is that you cannot use `rassq' (see below) to find the
  766. element containing a given value.  When neither of these considerations
  767. is important, the choice is a matter of taste, as long as you are
  768. consistent about it for any given alist.
  769.    Note that the same alist shown above could be regarded as having the
  770. associated value in the CDR of the element; the value associated with
  771. `rose' would be the list `(red)'.
  772.    Association lists are often used to record information that you might
  773. otherwise keep on a stack, since new associations may be added easily to
  774. the front of the list.  When searching an association list for an
  775. association with a given key, the first one found is returned, if there
  776. is more than one.
  777.    In Emacs Lisp, it is *not* an error if an element of an association
  778. list is not a cons cell.  The alist search functions simply ignore such
  779. elements.  Many other versions of Lisp signal errors in such cases.
  780.    Note that property lists are similar to association lists in several
  781. respects.  A property list behaves like an association list in which
  782. each key can occur only once.  *Note Property Lists::, for a comparison
  783. of property lists and association lists.
  784.  - Function: assoc KEY ALIST
  785.      This function returns the first association for KEY in ALIST.  It
  786.      compares KEY against the alist elements using `equal' (*note
  787.      Equality Predicates::.).  It returns `nil' if no association in
  788.      ALIST has a CAR `equal' to KEY.  For example:
  789.           (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
  790.                => ((pine . cones) (oak . acorns) (maple . seeds))
  791.           (assoc 'oak trees)
  792.                => (oak . acorns)
  793.           (cdr (assoc 'oak trees))
  794.                => acorns
  795.           (assoc 'birch trees)
  796.                => nil
  797.      Here is another example in which the keys and values are not
  798.      symbols:
  799.           (setq needles-per-cluster
  800.                 '((2 . ("Austrian Pine" "Red Pine"))
  801.                   (3 . "Pitch Pine")
  802.                   (5 . "White Pine")))
  803.           
  804.           (cdr (assoc 3 needles-per-cluster))
  805.                => "Pitch Pine"
  806.           (cdr (assoc 2 needles-per-cluster))
  807.                => ("Austrian Pine" "Red Pine")
  808.  - Function: assq KEY ALIST
  809.      This function is like `assoc' in that it returns the first
  810.      association for KEY in ALIST, but it makes the comparison using
  811.      `eq' instead of `equal'.  `assq' returns `nil' if no association
  812.      in ALIST has a CAR `eq' to KEY.  This function is used more often
  813.      than `assoc', since `eq' is faster than `equal' and most alists
  814.      use symbols as keys.  *Note Equality Predicates::.
  815.           (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
  816.           
  817.           (assq 'pine trees)
  818.                => (pine . cones)
  819.      On the other hand, `assq' is not usually useful in alists where the
  820.      keys may not be symbols:
  821.           (setq leaves
  822.                 '(("simple leaves" . oak)
  823.                   ("compound leaves" . horsechestnut)))
  824.           
  825.           (assq "simple leaves" leaves)
  826.                => nil
  827.           (assoc "simple leaves" leaves)
  828.                => ("simple leaves" . oak)
  829.  - Function: rassq ALIST VALUE
  830.      This function returns the first association with value VALUE in
  831.      ALIST.  It returns `nil' if no association in ALIST has a CDR `eq'
  832.      to VALUE.
  833.      `rassq' is like `assq' except that the CDR of the ALIST
  834.      associations is tested instead of the CAR.  You can think of this
  835.      as "reverse `assq'", finding the key for a given value.
  836.      For example:
  837.           (setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
  838.           
  839.           (rassq 'acorns trees)
  840.                => (oak . acorns)
  841.           (rassq 'spores trees)
  842.                => nil
  843.      Note that `rassq' cannot be used to search for a value stored in
  844.      the CAR of the CDR of an element:
  845.           (setq colors '((rose red) (lily white) (buttercup yellow)))
  846.           
  847.           (rassq 'white colors)
  848.                => nil
  849.      In this case, the CDR of the association `(lily white)' is not the
  850.      symbol `white', but rather the list `(white)'.  This can be seen
  851.      more clearly if the association is written in dotted pair notation:
  852.           (lily white) == (lily . (white))
  853.  - Function: copy-alist ALIST
  854.      This function returns a two-level deep copy of ALIST: it creates a
  855.      new copy of each association, so that you can alter the
  856.      associations of the new alist without changing the old one.
  857.           (setq needles-per-cluster
  858.                 '((2 . ("Austrian Pine" "Red Pine"))
  859.                   (3 . "Pitch Pine")
  860.                   (5 . "White Pine")))
  861.           =>
  862.           ((2 "Austrian Pine" "Red Pine")
  863.            (3 . "Pitch Pine")
  864.            (5 . "White Pine"))
  865.           
  866.           (setq copy (copy-alist needles-per-cluster))
  867.           =>
  868.           ((2 "Austrian Pine" "Red Pine")
  869.            (3 . "Pitch Pine")
  870.            (5 . "White Pine"))
  871.           
  872.           (eq needles-per-cluster copy)
  873.                => nil
  874.           (equal needles-per-cluster copy)
  875.                => t
  876.           (eq (car needles-per-cluster) (car copy))
  877.                => nil
  878.           (cdr (car (cdr needles-per-cluster)))
  879.                => "Pitch Pine"
  880.           (eq (cdr (car (cdr needles-per-cluster)))
  881.               (cdr (car (cdr copy))))
  882.                => t
  883. File: elisp,  Node: Sequences Arrays Vectors,  Next: Symbols,  Prev: Lists,  Up: Top
  884. Sequences, Arrays, and Vectors
  885. ******************************
  886.    Recall that the "sequence" type is the union of three other Lisp
  887. types: lists, vectors, and strings.  In other words, any list is a
  888. sequence, any vector is a sequence, and any string is a sequence.  The
  889. common property that all sequences have is that each is an ordered
  890. collection of elements.
  891.    An "array" is a single primitive object directly containing all its
  892. elements.  Therefore, all the elements are accessible in constant time.
  893. The length of an existing array cannot be changed.  Both strings and
  894. vectors are arrays.  A list is a sequence of elements, but it is not a
  895. single primitive object; it is made of cons cells, one cell per
  896. element.  Therefore, elements farther from the beginning of the list
  897. take longer to access, but it is possible to add elements to the list or
  898. remove elements.  The elements of vectors and lists may be any Lisp
  899. objects.  The elements of strings are all characters.
  900.    The following diagram shows the relationship between these types:
  901.                  ___________________________________
  902.                 |                                   |
  903.                 |          Sequence                 |
  904.                 |  ______   ______________________  |
  905.                 | |      | |                      | |
  906.                 | | List | |         Array        | |
  907.                 | |      | |  ________   _______  | |
  908.                 | |______| | |        | |       | | |
  909.                 |          | | String | | Vector| | |
  910.                 |          | |________| |_______| | |
  911.                 |          |______________________| |
  912.                 |___________________________________|
  913.           The Relationship between Sequences, Arrays, and Vectors
  914. * Menu:
  915. * Sequence Functions::    Functions that accept any kind of sequence.
  916. * Arrays::                Characteristics of arrays in Emacs Lisp.
  917. * Array Functions::       Functions specifically for arrays.
  918. * Vectors::               Functions specifically for vectors.
  919. File: elisp,  Node: Sequence Functions,  Next: Arrays,  Prev: Sequences Arrays Vectors,  Up: Sequences Arrays Vectors
  920. Sequences
  921. =========
  922.    In Emacs Lisp, a "sequence" is either a list, a vector or a string.
  923. The common property that all sequences have is that each is an ordered
  924. collection of elements.  This section describes functions that accept
  925. any kind of sequence.
  926.  - Function: sequencep OBJECT
  927.      Returns `t' if OBJECT is a list, vector, or string, `nil'
  928.      otherwise.
  929.  - Function: copy-sequence SEQUENCE
  930.      Returns a copy of SEQUENCE.  The copy is the same type of object
  931.      as the original sequence, and it has the same elements in the same
  932.      order.
  933.      Storing a new element into the copy does not affect the original
  934.      SEQUENCE, and vice versa.  However, the elements of the new
  935.      sequence are not copies; they are identical (`eq') to the elements
  936.      of the original.  Therefore, changes made within these elements, as
  937.      found via the copied sequence, are also visible in the original
  938.      sequence.
  939.      If the sequence is a string with text properties, the property
  940.      list in the copy is itself a copy, not shared with the original's
  941.      property list.  However, the actual values of the properties are
  942.      shared.  *Note Text Properties::.
  943.      See also `append' in *Note Building Lists::, `concat' in *Note
  944.      Creating Strings::, and `vconcat' in *Note Vectors::, for others
  945.      ways to copy sequences.
  946.           (setq bar '(1 2))
  947.                => (1 2)
  948.           (setq x (vector 'foo bar))
  949.                => [foo (1 2)]
  950.           (setq y (copy-sequence x))
  951.                => [foo (1 2)]
  952.           
  953.           (eq x y)
  954.                => nil
  955.           (equal x y)
  956.                => t
  957.           (eq (elt x 1) (elt y 1))
  958.                => t
  959.           
  960.           ;; Replacing an element of one sequence.
  961.           (aset x 0 'quux)
  962.           x => [quux (1 2)]
  963.           y => [foo (1 2)]
  964.           
  965.           ;; Modifying the inside of a shared element.
  966.           (setcar (aref x 1) 69)
  967.           x => [quux (69 2)]
  968.           y => [foo (69 2)]
  969.  - Function: length SEQUENCE
  970.      Returns the number of elements in SEQUENCE.  If SEQUENCE is a cons
  971.      cell that is not a list (because the final CDR is not `nil'), a
  972.      `wrong-type-argument' error is signaled.
  973.           (length '(1 2 3))
  974.               => 3
  975.           (length ())
  976.               => 0
  977.           (length "foobar")
  978.               => 6
  979.           (length [1 2 3])
  980.               => 3
  981.  - Function: elt SEQUENCE INDEX
  982.      This function returns the element of SEQUENCE indexed by INDEX.
  983.      Legitimate values of INDEX are integers ranging from 0 up to one
  984.      less than the length of SEQUENCE.  If SEQUENCE is a list, then
  985.      out-of-range values of index return `nil'; otherwise, they produce
  986.      an `args-out-of-range' error.
  987.           (elt [1 2 3 4] 2)
  988.                => 3
  989.           (elt '(1 2 3 4) 2)
  990.                => 3
  991.           (char-to-string (elt "1234" 2))
  992.                => "3"
  993.           (elt [1 2 3 4] 4)
  994.                error-->Args out of range: [1 2 3 4], 4
  995.           (elt [1 2 3 4] -1)
  996.                error-->Args out of range: [1 2 3 4], -1
  997.      This function duplicates `aref' (*note Array Functions::.) and
  998.      `nth' (*note List Elements::.), except that it works for any kind
  999.      of sequence.
  1000. File: elisp,  Node: Arrays,  Next: Array Functions,  Prev: Sequence Functions,  Up: Sequences Arrays Vectors
  1001. Arrays
  1002. ======
  1003.    An "array" object refers directly to a number of other Lisp objects,
  1004. called the elements of the array.  Any element of an array may be
  1005. accessed in constant time.  In contrast, an element of a list requires
  1006. access time that is proportional to the position of the element in the
  1007. list.
  1008.    When you create an array, you must specify how many elements it has.
  1009. The amount of space allocated depends on the number of elements.
  1010. Therefore, it is impossible to change the size of an array once it is
  1011. created.  You cannot add or remove elements.  However, you can replace
  1012. an element with a different value.
  1013.    Emacs defines two types of array, both of which are one-dimensional:
  1014. "strings" and "vectors".  A vector is a general array; its elements can
  1015. be any Lisp objects.  A string is a specialized array; its elements
  1016. must be characters (i.e., integers between 0 and 255).  Each type of
  1017. array has its own read syntax.  *Note String Type::, and *Note Vector
  1018. Type::.
  1019.    Both kinds of arrays share these characteristics:
  1020.    * The first element of an array has index zero, the second element
  1021.      has index 1, and so on.  This is called "zero-origin" indexing.
  1022.      For example, an array of four elements has indices 0, 1, 2, and 3.
  1023.    * The elements of an array may be referenced or changed with the
  1024.      functions `aref' and `aset', respectively (*note Array
  1025.      Functions::.).
  1026.    In principle, if you wish to have an array of characters, you could
  1027. use either a string or a vector.  In practice, we always choose strings
  1028. for such applications, for four reasons:
  1029.    * They occupy one-fourth the space of a vector of the same elements.
  1030.    * Strings are printed in a way that shows the contents more clearly
  1031.      as characters.
  1032.    * Strings can hold text properties.  *Note Text Properties::.
  1033.    * Many of the specialized editing and I/O facilities of Emacs accept
  1034.      only strings.  For example, you cannot insert a vector of
  1035.      characters into a buffer the way you can insert a string.  *Note
  1036.      Strings and Characters::.
  1037.